BBS Toolkit

home *** CD-ROM | disk | FTP | other *** search

/ BBS Toolkit / BBS Toolkit.iso / pc_board / pcbss30.zip / SS.DOC < prev next >

Wrap

Text File | 1992-11-23 | 73KB | 1,761 lines

PCBSuperScript v3.0 ───────────────────── ─────────────── ───────── ─── ─ Copyright (c) 1990-1992 by Chris Curran and Aquila Data Systems, Inc. All rights reserved. All trademarks and copyrights belong to their respective holders. Products Used ----------------------------------------------------------------------------- C compiler : Borland C++ v3.1 (Borland) Assembler : TASM v3.0 (Borland) Linker : TLink v5.1 (Borland) Debugger : TDebug v3.0 (Borland) Version Control: PVCS for DOS (Sage Software) Editor : QEdit 2.15 (SemWare) Disclaimer ----------------------------------------------------------------------------- The author hereby disclaims all warranties relating to this product, whether express or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. The author cannot and will not be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if the author or an authorized agent has been advised of the possibility of such damages. In no event shall the liability for any damages ever exceed the price paid for the license to use the software, regardless of the form and/or extent of the claim. The user of this program bears all risk as to the quality and performance of the software. License ----------------------------------------------------------------------------- PCBSuperScript is a Shareware product. As such, it is made available to the general personal computing public for evaluation. Users are licensed to operate this program on their personal computers for the purpose of test and evaluation on a trial basis for a limited trial period. It is not possible to reasonably define the limits of a fair and equitable time period for evaluation; therefore it is left to the user's judgment and sense of fair play as to the time required to make a decision as to its usefulness. If the user decides the program is not of sufficient merit to warrant purchase through registration with the author, he/she should remove the program from his/her personal computer. Otherwise, if the program is deemed useful and is in regular use on the user's computer system, registration with the author is required. Registered users are those users who elect to pay for PCBSuperScript and register that payment with the author. By virtue of registration and payment for the program, registered users are granted a license to continue to utilize the program on their personal computer for as long as they choose. This license authorizes the user to use the program on any personal computer system he or she may own or use so long as the program is operated on only one computer system at a time. Guarantee ----------------------------------------------------------------------------- PCBSuperScript is offered with an unconditional 30-day money-back guarantee. If you become dissatisfied with the program for any reason within that period, just let me know and your registration fee will be refunded. If you purchased a registration package which included a diskette and/or a manual, please return these when requesting a refund. This guarantee is unconditional. I would ask, however, if you are having a problem to let me know before giving up on PCBSuperScript since your problem may be something I can solve. Finally, if you order a registration package which includes a diskette or manual and either of these items are defective -- either through my error or through postal service "processing", let me know and I will send replacements promptly. Registration ----------------------------------------------------------------------------- The registration fee is $35, payable to: Aquila Data Systems 304 Bayfield Drive Brandon, FL 33511 The payment of this registration fee to the author entitles the user to full use of the product for an unlimited period of time in addition to product support. The distribution of diskette copies of PCBSuperScript and future upgrades is not included as part of the basic registration fee. See the ORDER.SS file for the charges associated with these services. PCBSuperScript is the sole property of Chris Curran. The program may be freely copied and transferred to individual parties for evaluation purposes. It may be posted on Bulletin Board systems (BBS) for electronic access as long as NO FEE is charged for its distribution except for private BBS operations that charge a regular user subscription fee. Computer information services such as Compuserve (CIS), Genie, and Byte Information Exchange (BIX) are authorized to post this product for subscriber access. PCBSuperScript may be distributed on diskette only by 1) disk distributors/vendors who are associate members of the Association of Shareware Professionals (ASP) or 2) users groups which do not charge more than a nominal fee ($5) to cover the costs of distribution. Any changes to these policies must be made in writing by the author. PCBSuperScript is a fully functional Shareware product. Shareware is a computer program distribution/marketing method that permits potential buyers to thoroughly try the program prior to purchase. It is NOT free and it is not in the Public Domain. If, after evaluating the program, you find it useful enough to use on a regular basis, you are expected to pay for it by registering with the author. Attractively-priced site licensing is available for commercial users. Pricing for "typical" site licensing is given later in this manual. If you have needs which are not met by the standard license terms, please call or write for a quote which addresses any unique support or product update requirements. Customization is also available on a contract basis. There has been some confusion in Shareware circles recently about upgrade/update policies for certain pieces of software. Therefore, I'd like to take this opportunity to spell out my policies. First, some definitions: I define upgrade as the RIGHT to use a later revision of a piece of software. I define update as the physical media on which the upgrade resides. I'll further define an update as not including hard-copy documentation unless specifically defined. With that out of the way, I'd like to spell out my current upgrade/update policies: There are no upgrade charges associated with PCBSuperScript and I do not have any plans at present to institute such charges with future revisions. I do reserve the right to do so, however, if in my sole opinion the nature and magnitude of PCBSuperScript changes to such a degree as to constitute an essentially new product. I currently do charge for updates and plan to continue to so charge. The content and pricing for specific update packages is contained in the ORDER.SS file. Pricing is subject to change without notice however, to accommodate postage, printing, and other price increases. Distributing PCBSuperScript ----------------------------------------------------------------------------- PCBSuperScript may be freely distributed (subject to the for-charge distribution restrictions detailed in the Registration section). Therefore, please feel free to distribute copies of this program to friends, co-workers, bulletin boards, and users' groups. I do ask, however, that you please distribute all of the original files and not modified copies. Thank you in advance for your cooperation. Technical Support ----------------------------------------------------------------------------- ┌─ Registered Users: Full technical support is available to registered │ users of PCBSuperScript. I have found that the most effective product │ support can be delivered through the electronic services listed below. If │ this option is not open to you, however, I also offer full product support │ through the mails, or, if the problem absolutely cannot wait, the │ telephone (no collect calls please). I will do my best to resolve any │ software bugs in a timely manner and I am always open to incorporating new │ features or changes which are appropriate to the nature of the product. │ ├─ Unregistered Users: I will attempt to respond to software trouble │ reports made by non-registered users if the problems affect the general │ functionality of the program. Such users should not, however, expect │ product support beyond initial aid to determine if the program is suitable │ for their needs. │ │ All Users: If you have a problem: I ask that, before calling or │ writing, you take the following steps: │ │ 1) Check the manual. We all sometimes approach a piece of software │ with preconceived ideas about how it ought to work which may not │ correspond to how it actually does work. (Of course, I'm │ interested in your input if you have this sort of experience.) │ │ 2) Have you loaded any new TSR's? Changed DOS versions? Modified any │ system files (CONFIG.SYS or AUTOEXEC.BAT) recently? Check to make │ sure these changes were done properly. │ │ 3) Run a CHKDSK on your system. It's a basic thing, but we sometimes │ forget about it (at least I do). │ │ 4) If you're still stuck, please aquire the following information │ and upload it to QExchange BBS: │ │ a) Your hardware and software environment. PCBSuperScript is a very │ versatile program and, unfortunately, one of the downsides of │ this versatility is that settings can sometimes interact in │ unexpected ways. I try to test a broad range of environments │ and settings, but obviously can't try every one. │ │ b) The sequence of actions which lead to the error. If I can't │ reproduce the error, it will be very difficult to correct it, so │ your help is vital in isolating the problem. │ │ c) The PCBSS definition file and ALL associated files for that │ definition file (i.e. environment settings, PORT settings, │ etc.) │ │ *************************************************************** └─────── * If you do not following the above steps for reporting PCBSS * * problems, I cannot help you. If you leave a message asking * * for help WITHOUT the above information, it will be IGNORED. * * * * This applies to registered and unregistered users alike. * *************************************************************** If you follow these steps, it will help me to solve your problem in a more efficient and timely manner. Contact via: QExchange BBS Line #1 (813)653-2937 1200-57,600 v.32/42 bis Line #2 (813)685-4218 1200-57,600 v.32/42 bis U.S. Mail Aquila Data Systems 304 Bayfield Drive Brandon, FL 33511 Abstract ----------------------------------------------------------------------------- PCBSuperScript is a script processing language specificaly designed to meet the needs of PCBoard Sysops. Since PCBSuperScript is a script processor, some degree of planning will be necessary. Just like you have to plan out (and test) large and advanced BAT files, you'll have to plan out the PCBSuperScript files. PCBSuperScript offers control features that are similar to many programming languages. You do not need to use all the features of PCBSuperScript, but if you want to use it to it's fullest, some degree of programming background will help. Before you become scared away from PCBSuperScript because you don't know programming, keep in mind that only advanced needs will require advanced scripts. Start off simple and work up to the advanced level. If you find the task impossible, leave me an example on my BBS and I'll try to point you in the right direction. I won't write the script for you, but I will advise on the method to use. Some of the things you can perform with PCBSuperScript: o You can create your own doors, without being a programmer. o You can use a large number of testing methods, and react to caller entry in an intelligent manner. You can ask questions based on the result of a previous question, execute only certain portions of a script, provide default answers to questions, provide field formatting instructions, etc... o PCBSuperScript field entry can require a minimum and maximum number of char's to be entered, allow only certain types of data to be entered (char or numeric) and automatic formatting of phone number type fields. o YOU have direct control over what, and how data is written to the log file. o A PCBSuperScript script can be limited to callers with a specific security level, and also require a password to enter it. o PCBSuperScript only displays what you tell it to; you don't have to have the first six lines of anything displayed. o You can modify the caller security level. o You can place entries in the caller log. o You can send a message to the caller, yourself or anyone else, in any conference. o Shell to any DOS program, or perform any DOS command. Unlike most other data acquisition doors (i.e. registration doors), PCBSuperScript does not bind you to one method/format of acquiring user input, or the purpose for which it's used. PCBSuperScript can be used for almost anything, but I use it for the following purposes on my BBS: o New caller registration, with immediate security update's (and a COMMENT sent to SYSOP). o General Q&A of the caller. o Accepting software bug reports. o Processing on-line orders. o Specialized file transfers. Requirements ─────────────────────────────────────────────────────────────────────────── PCBSuperScript requires: o PCBoard version 14.5 or higher. o 90-256k free memory (128k typical), depending on size the of script loaded. NOTE: If you are *not* using version 14.5a of PCBoard (the current release), you will need to SET a few environment variables in your BOARD.BAT file. They are: PCBDRIVE PCBoard's home drive letter PCBDIR PCBoard's home directory PCBDAT name/location of PCBOARD.DAT Example: SET PCBDRIVE = J: SET PCBDIR = \PCB SET PCBDAT = J:\PCB\PCBOARD.DAT Installing PCBSuperScript ─────────────────────────────────────────────────────────────────────────── Installing PCBSuperScript is as easy as copying the file SS.EXE to your PCBoard door directory. Then for each door that you wish to create, you'll need to create the door driver and definition files. The door driver file is the file that PCBoard uses to execute the door. For example, if you wanted to setup a door named "INFO", you would create a file named "INFO" (no extension) in your PCBoard directory. The contents of this file would look something like the following: @echo off ss j:\pcb\ss\info.def exit This example would load PCBSuperScript with the definition file "J:\PCB\SS\INFO.DEF". PCBSuperScript does not require that you supply the drive and path to the definition file - I just always include such information to keep confusion down to a minimum (my own). You will then need to use PCBSETUP to add the door to DOOR.LST as follows: ┌───────────────────────────────────────────────────────────────────────┐ │ USER DOOR │ │ Filename Password Sec Login SYS SYS Shell Path to DOOR Files │ │ ══════════ ════════════ ═══ ═════ ════ ════ ═════ ═══════════════════╡ │ 1) INFO 9 Y Y N N J:\PCB\SS │ └───────────────────────────────────────────────────────────────────────┘ | +-edit accordingly Filename The name of the door. Password Optional password for this door. Sec Security level needed to open this door. Login 'Y' if this is a login door, 'N' otherwise. USER SYS ALWAYS set to 'Y' for PCBSuperScript doors. DOOR SYS ALWAYS set to 'N' for PCBSuperScript doors. Shell Determines how PCBoard will shell to the door. NOTE: If you set this field to 'N', you *must* replace the "exit" verb in the door driver file with "board". Path Optional path to door files. General Description of Scripts ─────────────────────────────────────────────────────────────────────────── Script Definition ───────────────── A script file is a standard DOS ASCII file that contains a list of commands to perform. All PCBSuperScript script files are standard ASCII text files. These files are created and maintained in much the same manner as your AUTOEXEC.BAT and CONFIG.SYS files are. Do NOT use MS Word, WordPerfect or other similar word processors to create/maintain script files. A text editor will be needed for this purpose (QEdit being my personal choice). A script file cannot be larger than 62k. Script Labels ───────────── Labels are "place markers" used by your script. Your script will refer to labels for various reasons, but most of the time they are used in combonation with a GOTO or GOSUB command. Labels are alpha-numeric and begin or end with a colon (":"). Script Comments ─────────────── The ';' character is used as a comment character in script files. The comment character may begin at any position on the line. Script lines that are entirely comment lines are not loaded into memory. There are no memory or performance penalties for using comments in your scripts. NOTE: If the comment character needs to be used in a string, it should be enclosed between matching quotes. Script Parsing ────────────── The command parsing of PCBSuperScript is different than what most users are probably familiar with, but you'll soon discover that it is very easy and powerful at the same time. PCBSuperScript parses the script files one word at a time. A "word" to PCBSuperScript is any text separated by a space(s), tab character(s) or any text enclosed by matching quotes. All spaces and tabs are removed from between words while processing. Therefore, if you are using a parameter that contains one or more spaces, you must enclose it in matching quotes so that the spaces are not removed. It is important to understand the usage of quotes in PCBSuperScript. Since PCBSuperScript allows "stacking" of text and variables in a script line, there must be some way for it to discern variables from literal text. Whenever PCBSuperScript encounters a quote (single or double), it will search for the next matching quote. The data between the matching quotes is then treated as one "word". While PCBSuperScript is processing a script line, each word is checked against the variable table first; if a match is found, the value of the variable is accumulated internally. If a match is not found, the word itself is accumulated. Remember, text enclosed by matching quotes is treated as one word; regardless of the number of spaces it contains. The final result is a combination of all variables and literal text in the script line. For example, the following commands will display different results to the screen due to the different usage of quotes: COMMAND: TEXT "Display this data to the screen" RESULT: Display this data to the screen COMMAND: TEXT Display this data to the screen RESULT: Displaythisdatatothescreen As was noted earlier, PCBSuperScript allows "stacking" of text and variables in a script line. The following example demonstrates this: COMMAND: TEXT "Date: " @sysdate@ " Time: " @systime@ RESULT: Date: 06-17-91 Time: 04:28 COMMAND: TEXT Date: @sysdate@ Time: @systime@ RESULT: Date:06-17-91Time:04:28 Again, note the usage of quotes, and the results. Tutorial ─────────────────────────────────────────────────────────────────────────── This section is a tutorial on the basic use of PCBSuperScript. It is recommended that all users complete this section, regardless of previous experience. The following sections instruct you to create, and add text to three files: NEWCALL, NEWCALL.MSG and NEWCALL.DEF. These files are also included with this ZIP file (in case you do not wish create and enter these files). However, you should check these files for directory specific items, and change accordingly. Also note that there are a number of sample scripts for PCBSuperScript included ("*.DEF"). They should be printed out and studied at your leisure. PCBoard Macros and Environment Variables ─────────────────────────────────────────────────────────────────────────── The following PCBoard Macros are available: Caller Information ────────────────── @bps@ Connect Speed @city@ City @comment1@ Comment line 1 @comment2@ Comment line 2 @confnum@ Current Conference Number @dataphone@ Business/Data Phone @daybytes@ Daily D/L Bytes @dlbytes@ Total D/L Bytes @dlfiles@ Total D/L Files @expertmode@ Expert mode @expdate@ Expiration Date @file_stat@ Status of last PCBSuperScript file command @first@ First Name (first letter capitalized) @firstu@ First Name (all caps) @graphics@ 0 = not in graphics mode, 1 = in graphics mode @homephone@ Home/Voice Phone @lastdateon@ Last Date On @lasttimeon@ Last Time On @minleft@ Minutes Left @msgleft@ Number of Messages Written @msgread@ Number of Messages Read @numtimeson@ Number of Times On @pagelen@ Page length setting @password@ User password @port@ Port id @proltr@ Default Protocol Letter @security@ Security Level @shell_stat@ Status of last PCBSuperScript shell command @timelimit@ Time Limit @timeused@ Time Used @totaltime@ Total Time Used so far Today @upbytes@ Total U/L Bytes @upfiles@ Total U/L Files @user@ Full Name (all caps) System Information ------------------ @boardname@ Name of the BBS you are on @event@ Event Time @node@ Node Number @sysdate@ Current Date @systime@ Current Time @ss_version@ PCBSuperScript version number Display Controls ---------------- @automore@ treats "more?" prompts in a file like @pause@ @beep@ sends a CTRL-G (ascii BELL character) to the caller but is not heard on the local machine unless the Caller Alarm is turned on @cls@ clear the entire screen @clreol@ clear from the cursor to the end of the line @more@ cause a "more?" prompt to be displayed @pause@ displays a "more?" prompt with a 10 second auto return if the caller doesn't answer it first @poff@ Turns Prompts OFF (disables "more?" prompt) @pon@ Turns Prompts ON (enables "more?" prompt) @qoff@ disables CTRL-X/CTRL-K checking (display abort) @qon@ enables CTRL-X/CTRL-K checking (display abort) @wait@ display a "press enter to continue" prompt Environment variables are variables that are currently defined in your DOS environment. Environment variables are accessed in the following manner: @%name Access environment variable "name". Whenever a PCBoard Macro or Environment variable is referenced in a script, the current value of the variable is substituted for the variable name. Script Variables ─────────────────────────────────────────────────────────────────────────── Variables must be declared in the script file prior to usage, and are defined in the following manner: FIELDS <name> <type> <len> <prec> <min> <mask> <default> ....... ....... <name> <type> <len> <prec> <min> <mask> <default> FIELDS The command "FIELDS" is used to mark the beginning and end of a list of script variables. Lines between matching "FIELDS" keywords, are considered field descriptor lines. The format of a descriptor line is: name The name of the variable. 1 to 32 char's. Case *is* significant. If the variable name is already defined, this definition will be ignored. type The type of the field. 1 char. 'C' Character field. 'N' Numeric field. len The length of this variable. For 'C' type fields, this should be the TOTAL length of the field, including any mask characters, etc. If the field is type 'N', this represents the number of digits to the left of the decimal point. prec The precision of this variable. If the field type is 'C', the precision is forced to 0. For 'N' type fields, this represents the number of digits to the right of the decimal point. min The minimum entry length of this variable (in an ACCEPT or PROMPT command). mask The entry mask. The "mask" field provides PCBSuperScript with information on how it should handle user entry for this variable. The mask is a combination of special formatting characters and literal text that describes how each character of the field should be handled. A mask may consist of literal characters or any of the following special characters: % digits, space, minus, dot 9 digits ONLY * any char ! printable only a space,alpha,num char's only (tolower) A space,alpha,num char's only (toupper) h hex char's only (tolower) H hex char's only (toupper) Y Yes or No P Protected. A dot ('.') is eched back to the caller. <> Inclusion set. Char's between matching <> are considered the only allowable char's for the position marked by '<'. See 'Option' field below. If the length of the mask is less than the defined length of the variable, the mask is expanded to the defined length. The last character in the mask is used for the expansion. See 'Name' field below. default The default value of the field (optional). This can be any text enclosed by matching quotes, system variables or environment variables (see System Variables). The following FIELDS block defines a commonly required group of variables: FIELDS Option C 1 0 1 <ALEale> Name C 25 0 0 *! @user@ Company C 25 0 3 ! Addr C 25 0 5 ! CitySt C 25 0 5 ! @city@ Zip C 5 0 5 99999 Country C 15 0 3 ! USA Phone C 13 0 13 (999)999-9999 Fax C 13 0 0 (999)999-9999 Num2Call C 45 0 0 * Age C 2 0 2 99 How C 25 0 0 ! Occup C 25 0 0 ! PCType C 25 0 0 ! NetWork C 25 0 0 ! FIELDS Note the usage of "@user@" and "@city@". These are two of the available system variables (or macros), and are used here to provide a default answer for the appropriate fields. The "Country" field uses a literal text default value of "USA". Any number of FIELDS blocks may be defined, provided not more that 500 variables are defined at any one time (see RELEASE below). When a variable is defined, it will continue to "exist" until PCBSuperScript is exited, or it is released with the RELEASE command. This allows you to easily share data between different scripts (using the CALL or RUN command). Displaying information to the caller ─────────────────────────────────────────────────────────────────────────── The TEXT command is one of the commands that can be used to display data to the caller. The data displayed may contain a combination of literal data, field names, system variables and environment variables. The combination of all data (the final result) may not exceed 512 char's PER LINE. PCBoard @X color codes are recognized. The NEWLINE command is used to display one or more blank lines to the screen. The maximum number of blank lines that may be displayed is "limited" to 65,535. Issueing a "NEWLINE 25" will fake a clear screen on the caller's screen; in either graphics mode. The INDENT command is used to position the displayed text to a specific column. Add the following lines to "NEWCALL.DEF": NEWLINE 24 INDENT 5 TEXT "---------------------------------------------------------------" TEXT " **** A Great Bulletin Board ****" TEXT "---------------------------------------------------------------" NEWLINE 2 TEXT "You are in the new caller login section. After completing" TEXT "the questions below, you will be returned to the main bulletin" TEXT "board." TEXT "" TEXT "This is a one-time procedure. Estimated time to complete this" TEXT "questionnaire is 2 to 4 minutes." TEXT "" TEXT " Date: " @sysdate@ TEXT " Time: " @systime@ TEXT " Caller Name: " @user@ TEXT " City, State: " @city@ TEXT " Security Level: " @security@ TEXT " Baud Rate: " @bps@ TEXT " Node: " @node@ TEXT "" TEXT "---------------------------------------------------------------" TEXT "" INDENT 0 Another command that is used to display data to the caller is "DISPLAY_FILE". This command will display the contents of a file to the screen. Add the following line to "NEWCALL.DEF": DISPLAY_FILE J:\PCB\SS\NEWCALL.MSG | +-edit accordingly Data Entry ─────────────────────────────────────────────────────────────────────────── Before discussing data entry commands, field masks need to be explained. A field mask could be thought of as a 'template' for how each character in the field should be entered. Field masks are defined with the variable in a FIELDS block, or inline with the SETMASK command. A field mask is comprised of mask characters, literal characters and inclusion sets (each is defined below). For each position in the field that a character will be entered, a mask characacter must be used as a 'place holder'. mask char Characters entered in this position are checked for validity based on the mask character used: Char Characters allowed at position ---------------------------------------------------- % Digits, space, minus, dot 9 Digits ONLY * Any char ! Printable only a Space,alpha,num char's only (conv to lower) A Space,alpha,num char's only (conv to upper) h Hex char's only (conv to lower) H Hex char's only (conv to upper) Y Yes or No P Protected. A dot ('.') is eched back to the caller. literal Any character not in the above set (including spaces). If one of the above characters is needed as a literal character, preceed it with a backslash ('\'). Literal characters are copied to the input field. The cursor will not 'sit' on a literal character. inclusion Characters entered in this position are checked against a provided list of 'valid' characters. The valid characters are enclosed by "<>". Examples: Name C 25 0 0 *! @user@ This field mask will allow any character to be entered in the first position of the field, and any printable chacater in the remaining 24 positions. NOTE: Since the mask was defined with length of 2 ("*!"), PCBSuperScript will expand this at the time of definition to "*!!!!!!!!!!!!!!!!!!!!!!!!". Phone C 13 0 13 (999)999-9999 This field mask will allow digits at positions 2-4, 6-8 and 10-13. The cursor will not be allowed to rest on positions 1, 5 and 9. The characters '(', ')' and '-' will autofill at entry time, and will be copied to the field variable upon entry. Option C 1 0 1 <ALEale> This field mask uses an inclusion set to allow entry of the letters 'A', 'L', 'E', 'a', 'l' and 'e'. Any other character will be ignored for this position. There are two commands that are used to perform data entry in PCBSuperScript. The first command, 'PROMPT', does not require an ANSI driver. The PROMPT command will work regardless of the graphics mode of the caller. The second command, 'ACCEPT' requires that an ANSI driver be present (i.e. caller in graphics mode). This command allows you to directly address row/col coordinates on the screen (i.e full screen operations). When the caller is in non-graphics mode and the script uses an ACCEPT command, it will be internally converted to a PROMPT command. Any row/col information is ignored and the resulting display may not be what you expect. You should experiment with this feature in both graphics modes to verify that your scripts operate as expected. NOTE: Both commands utilize the field mask in the same manner. The PROMPT command has the following format: PROMPT prompt_msg variable where: prompt_msg the prompt displayed to the caller variable the variable name used to store the caller's entry. Example: ; ; Field definitions ; FIELDS Option C 1 0 1 <ALEale> Name C 25 0 0 *! @user@ Company C 25 0 3 ! Addr C 25 0 5 ! CitySt C 25 0 5 ! @city@ Zip C 5 0 5 99999 Country C 15 0 3 ! USA Phone C 13 0 13 (999)999-9999 Fax C 13 0 0 (999)999-9999 Num2Call C 45 0 0 * Age C 2 0 2 99 How C 25 0 0 ! Occup C 25 0 0 ! PCType C 25 0 0 ! NetWork C 25 0 0 ! FIELDS ; ; Field entry ; PROMPT " Company: " Company PROMPT " Address: " Addr PROMPT " City, State: " CitySt PROMPT " Zip: " Zip PROMPT " Country: " Country PROMPT " Phone Number: " Phone PROMPT " Fax/Data Number: " Fax PROMPT " Your Age: " Age NEWLINE PROMPT " Your occupation: " Occup PROMPT " How did you hear of QExchange?: " How PROMPT " What type of PC do you use?: " PCType PROMPT " PC NetWork (if you use one): " NetWork ; ; all done... ; EXIT Changing the field mask ----------------------- Most of the time the entry mask that's defined with a field is sufficient for the entire run of the script. There are times however, that changing the entry mask at run time is desirable. An example is a field that's used to store the result of an "option" type of prompt. For example: setmask Option "<123>" ;set new entry mask Option prompt "Select option 1, 2 or 3" Option ... ... setmask Option "<ABCabc>" ;set new entry mask Option prompt "Select option A, B or C" Option Escape Checking during data entry --------------------------------- If you want to allow the caller to press ESC to abort entry of the current field, use the ESC_CHK command ("ESC_CHK ON"). If the caller presses ESC, the contents of the field is restored and the system variable '@esc_pressed@' is set to '1'. You can test for this with the following code: ESC_CHK ON ;turn escape checking on PROMPT " Name: " Name ;get name from caller IF @esc_pressed@ == 1 ;chk for esc press GOTO AbortJob ; abort script if pressed ENDIF ; This method works fine if you're only inputing one field, but if the script is accepting input of multiple fields, you may wish to use the 'ESC_TO' command. This command is used to set a label that the script will jump to if esc is pressed in a PROMPT or ACCEPT command. :AddRec ESC_CHK ON ;turn escape checking on ESC_TO AddRec99 ;set ESC_TO label PROMPT " Name: " Name ;get name from caller ..... ..... :AddRec99 ;exit label ESC_TO ;reset ESC_TO label ESC_CHK OFF ;turn escape checking on RETURN ;return to caller Automatic Enter --------------- The command AUTOENTER ON/OFF can cause PCBSuperScript to simulate a press of the <ENTER> key when the caller reaches the end of the current entry field. This command can be used with a 1 character field to provide "hot-key" fields. See NEWCALL.DEF for an example. Forcing the caller to press ENTER --------------------------------- Displays a "Press Enter to continue..." prompt, and waits for the caller to press ENTER. Clearing the keyboard --------------------- The FLUSH_KB command will clear the keyboard buffer. This is usefull when you want to defeat the type-ahead allowed by PCBoard. For example: flush_kb ;clear kb in case they've already pressed ENTER force_enter ;make caller press enter Barking at the caller --------------------- The BEEPS ON/OFF command sets the beep mode of the PCBSS PROMPT and ACCEPT commands. If BEEPS ON is in effect, PCBSS will beep the caller when they've reached the end of an input area. If BEEPS OFF is in effect, PCBSS will simply stop at the end of the input area. Example: beeps off ;don't bark at caller setmask Option "<ABCabc>" ;set new entry mask Option prompt "Select option A, B or C" Option ;get caller input Free form data entry -------------------- The GETMSG command is used to accept input of free form blocks of text from the caller. The GETMSG has the same commands, and acts in the same manner as PCBoard full screen message entry. This command is most often used to get caller comments, special instructions, etc... Note that the caller must be in graphics mode for this command to function correctly. GETMSG <format> <srow> <scol> <rows> <cols> format The name of the FORMAT for this message. srow The starting row of the message entry area. scol The starting col of the message entry area. rows The number of DISPLAY rows of the msg. The number of message rows are deduced from the the number of fields defined in the format used with this msg command. cols The number of display columns for this message entry area. Example: FIELDS shpins1 C 30 0 0 "*" "" shpins2 C 30 0 0 "*" "" shpins3 C 30 0 0 "*" "" shpins4 C 30 0 0 "*" "" shpins5 C 30 0 0 "*" "" shpins6 C 30 0 0 "*" "" shpins7 C 30 0 0 "*" "" shpins8 C 30 0 0 "*" "" shpins9 C 30 0 0 "*" "" shpins10 C 30 0 0 "*" "" FIELDS ... ... FORMAT MsgFmt shpins1 shpins2 shpins3 shpins4 shpins5 shpins6 shpins7 shpins8 shpins9 shpins10 FORMAT ... ... setmask Option "Y" ;set new entry mask Option prompt "Any special shipping instructions?" Option if Option == 'Y' getmsg MsgFmt 8 9 5 30 ;enter a msg at row 8, col 9. There ;will be 5 displayed rows and 30 ;display columns, but the caller can ;enter upto 10 message lines (rows). ;The message data will scroll as ;needed during entry. endif ... ... Saving Data ─────────────────────────────────────────────────────────────────────────── Data from scripts may be written to text files, dBase III files or both. Commands used with dBase files are discussed in the next section. The command "LOG_DATA" is used to write data to DOS text files. If the specified file currently exists, it will be appended to, otherwise, it will be created. Lines between matching "LOG_DATA" keywords, are considered log file descriptor lines. The format for a log file descriptor line is a variable combination of literal data, field names, system variables and environment variables. The combined total length of a log file descriptor line (after macro and variable expansion) may not exceed a length of 512. Add the following lines to "NEWCALL.DEF": ; ; Field definitions ; FIELDS Option C 1 0 1 <ALEale> Name C 25 0 0 *! @user@ Company C 25 0 3 ! Addr C 25 0 5 ! CitySt C 25 0 5 ! @city@ Zip C 5 0 5 99999 Country C 15 0 3 ! USA Phone C 13 0 13 (999)999-9999 Fax C 13 0 0 (999)999-9999 Num2Call C 45 0 0 * Age C 2 0 2 99 How C 25 0 0 ! Occup C 25 0 0 ! PCType C 25 0 0 ! NetWork C 25 0 0 ! FIELDS ; ; Field entry ; PROMPT " Company: " Company PROMPT " Address: " Addr PROMPT " City, State: " CitySt PROMPT " Zip: " Zip PROMPT " Country: " Country PROMPT " Phone Number: " Phone PROMPT " Fax/Data Number: " Fax PROMPT " Your Age: " Age NEWLINE PROMPT " Your occupation: " Occup PROMPT " How did you hear of QExchange?: " How PROMPT " What type of PC do you use?: " PCType PROMPT " PC NetWork (if you use one): " NetWork ; ; append data to log file ; TEXT "Logging data. Please wait..." LOG_DATA J:\PCB\SS\NEWCALL.LOG ;<── edit accordingly "-----------------------------------------------" " Name: " Name ", " Age " Company: " Company " Address: " Addr " City, State: " CitySt " Zip: " Zip " Country: " Country " Phone Number: " Phone " Fax Number: " Fax " Date/Time: " @sysdate@ @systime@ " Node/Port/Baud: " @node@ @port@ @bps@ "-----------------------------------------------" LOG_DATA ; ; all done... ; EXIT The log file result of this example might look something like the following: ----------------------------------------------- Name: Joe Smith, 32 Company: Acme Steel Address: 123 Metal Lane City, State: Iron Ore, PA Zip: 12345 Country: USA Phone Number: (123)456-7890 Fax Number: (000)000-0000 Date/Time: 12/27/90 09:46:19 Node/Port/Baud: 2 1 19200 ----------------------------------------------- dBase Files ─────────────────────────────────────────────────────────────────────────── dBase file records are accessed using a "FORMAT" block. A format block is a list of (previously defined) fields that will be used to transfer data between the file and your script. A FORMAT block is defined as follows: FORMAT <fname> <key flds...> <fld> ... FORMAT The keyword "FORMAT" is used to mark the beginning and end of a list of variables. fname The name of the format. 1 to 32 char's. Case *is* significant. key flds The name(s) of the fields in this format that comprise the key to a record (multiple key segments are supported). fld The name of a previously defined field. Example: FIELDS Name C 25 0 0 *! @user@ Company C 25 0 3 ! Addr C 25 0 5 ! CitySt C 25 0 5 ! @city@ Zip C 5 0 5 99999 Country C 10 0 3 ! USA Phone C 13 0 13 (999)999-9999 Fax C 13 0 0 (999)999-9999 Age C 2 0 2 99 How C 25 0 0 ! Occup C 25 0 0 ! PCType C 25 0 0 ! NetWork C 25 0 0 ! NetWork C 25 0 0 ! BankTime N 3 0 0 999 0 Num2Call C 45 0 0 * FIELDS FORMAT HistFmt Name Name Company Addr CitySt Zip Country Phone Fax Age How Occup PCType NetWork BankTime Num2Call FORMAT NOTE: Since you might need to access a dBase file from multiple scripts, it would be a good idea to store file specific FIELDS and FORMAT blocks into a seperate file that is "INCLUDED" into your script at runtime (see the INCLUDE command). This will also aid you in the future if/when you add/change or modify the variables used in a FORMAT block. If you put the FIELDS and FORMAT block directly in your scripts (rather than an INCLUDE file), you will have to hand modify EACH script that will access the file FORMAT you just changed. After the format(s) have been defined, you can open a dBase file and perform normal operations on that file (read, write, etc). You may have up to 10 files open at once. Each file that is used by the script is referenced by a 'handle'. Valid handle values are 0 through 9. The macro "@file_stat@" contains the result of the last dBase file operation performed by PCBSuperScript. All dBase file commands load this macro with "*OK*" if no error occurred. This macro should be checked after a dBase file function to insure proper script operation. If an error does occur during a dBase file command, the variables specified in the format are *not* modified. The following commands are used to perform dBase file operations: Command Parameters Description ─────────────────────────────────────────────────────────────────── CREATE <hdl> <format> <file> Create a dBase file OPEN <hdl> <file> Open an existing dBase file CLOSE <hdl> Close an open dBase file READ <hdl> <format> Read a record with key READF <hdl> <format> Read the first record READL <hdl> <format> Read the last record READP <hdl> <format> Read the previous record READN <hdl> <format> Read the next record WRITE <hdl> <format> Write record with key Creating dBase files -------------------- The CREATE command is used to create a dBase file if it does not exist. If the file already exist, CREATE will return an error (leaving the disk file alone). If the CREATE command does not result in an error, the file will be opened using the provided handle. The record pointer will be positioned to the first record in the file. ... ... FORMAT InvDetail rnbr rline rnbr ;invoice # (1st part of key) rline ;invoice line item number (last part of key) ritm ;inventory item # for this line item rqty ;quantity ordered for this line item rprice ;each price of this line item rdisc ;discount percent for this line item rupdate ;update flag for this record FORMAT ... ... create 1 InvDetail J:\AR\DATA\R1B ;try to create file if @file_stat@ != "*OK*" ;chk for err text "Cannot create J:\AR\DATA\R1B." ; report error force_enter ; make 'em press enter exit all ; exit endif ; ... Opening dBase files ------------------- The OPEN command is used to open a currently existing dBase file. If the file does not exist, OPEN will return an error (leaving the disk file alone). If the OPEN command does not result in an error, the record pointer will be positioned to the first record in the file. ... open 1 InvDetail J:\AR\DATA\R1B ;try to open file if @file_stat@ != "*OK*" ;chk for err text "Cannot open J:\AR\DATA\R1B." ; report error force_enter ; make 'em press enter exit all ; exit endif ; ... Reading dBase files ------------------- The READ command is used to read a specified record from a dBase file. If the specified key is not on file, an error is returned. Otherwise, the fields in the specified FORMAT block are loaded with the data from the READ. The key that is used to read the data file is built from the key fields in the specified FORMAT. For example, in the "HistFmt" defined above the field "Name" is the key field. The FORMAT "InvDetail" (above) will build the key from two fields: "rnbr" and "rline". read 1 HistFmt ;read caller hist file for this caller if @file_stat@ == "*OK*" ;was it found? set wasnew N ; gosub Listit ; yes; display and prompt else ; set wasnew Y ; gosub NewCaller ; endif ;not found, new caller There are four other commands that perform read type functions on dBase files: READF, READL, READP and READN. These commands read the first, last, previous and next records (respectivly) in a dBase file. Writing dBase files ------------------- The WRITE command is used to write a record to a dBase file. The key that is used to write the record is built from the key fields in the specified FORMAT. For example, in the "HistFmt" defined above the field "Name" is the key field. The FORMAT "InvDetail" (above) will build the key from two fields: "rnbr" and "rline". If the key that is formed is currently on file, it's record is over- written with the new record data. If the key is not on file, the key and record are added to the file. Techiques --------- A common need in most programming is control record processing. Let's say you're writing an order processing door. You need to store the order number in a control file so that it can be read for new orders, and updated after an order is placed. FIELDS ivcKey C 5 0 0 * FIELDS ... FORMAT InvCtrl ivcKey ivcKey ;invoice # control record key rnbr ;invoice # FORMAT ... ... open 1 InvCtrl J:\AR\DATA\R1CTRL ;try to open control file if @file_stat@ != "*OK*" ;chk for error goto fatalError ; exit script if error endif ;control file is now open set ivcKey "RNBR" ;set record key to read read 1 InvCtrl ;read control record if @file_stat@ != "*OK*" ;chk for error goto fatalError ; exit script if error endif ; ; ; the field 'rnbr' now contains the value read from the control ; file 'J:\AR\DATA\R1CTRL' using a key of "RNBR". ; ... ... ... ; ; add 1 to the order # and update the control file ; inc rnbr ;increment 'rnbr' field by 1 set ivcKey "RNBR" ;set record key to write write 1 InvCtrl ;write control record if @file_stat@ != "*OK*" ;chk for error goto fatalError ; exit script if error endif ; close 1 ;close the file Technical Notes ---------------- The dBase files that are maintained by PCBSuperScript are comprised of two files: the data file and the index file. The name of the data file will be the file name specified with an extension of ".DBF". The index file will have an extension of ".NDX". For example, if you used the CREATE command to create a file named "SALES", PCBSuperScript would create a file named "SALES.DBF" and a file named "SALES.NDX". The OPEN command also expects this file naming structure. The record key is defined in the format statement as a list of record variables that comprise the key. Therefore, you cannot have a variable as part of the key if it is not part of the data record. This will sometimes mean that you have to include a variable in the data record that you don't "really" need as part of the record. But this also means that if the index file is ever damaged it can be easily reconstructed. The key that PCBSuperScript builds from the data record is NOT case sensitive. The dBase key expression used is: UPPER(var1)+UPPER(var2)+....UPPER(varN) If the field is a numeric, the expression would be "UPPER(STR(varN))". When PCBSuperScript is building the key, the variable(s) used are padded with spaces to their defined lengths before forming the key. NOTE: The above case conversions and padding occurs internally. NO modifications are made to the variables defined in the format. Date/Time Commands ────────────────────────────────────────────────────────────────────────── The date/time commands provide your script with the ability to retrieve the date and time in a variety of formats. They also allow easy addition and subtraction of date fields. The command CURTIME will return the current time in one of six formats. Command: CURTIME <type> <var> Parms: type 0 05:58:48.26 1 05:58:48 2 5:58 AM 3 5:58a 4 5:58 5 05:58 var The name of the variable to store the time in. Example: CURTIME 1 xtime ;xtime = "05:58:48" CURTIME 3 xtime ;xtime = "5:58a" CURTIME 4 xtime ;xtime = "5:58" The command CURDATE will return the current date in one of thirteen formats. The <sep> parameter is the character used as a 'seperator' if the date format requires one. For example, using format type 5, there is a seperator between 'mm', 'dd' and 'yy' (i.e. 'mm-dd-yy'). Command: CURDATE <type> <sep> <var> Parms: type 0 Tuesday March 14, 1992 1 Tue March 14, 1992 2 March 14, 1992 3 14 Mar 92 4 m-d-yy 5 mm-dd-yy 6 d-m-yy 7 dd-mm-yy 8 yy-m-d 9 yy-mm-dd 10 m-d-yyyy 11 mm-dd-yyyy 12 mmddyy 13 yymmdd sep The seperator character used in types 4-11. var The name of the variable to store the time in. Example: CURDATE 1 '/' xdate ;xdate = "Tue March 14, 1992" CURDATE 4 '/' xdate ;xdate = "3/14/92" CURDATE 11 '-' xdate ;xdate = "03-14-1992" The command DATEADD will add the specified number of days to a date field. The date field that is being added to *must* be in 'mm-dd-yy' format (CURDATE format #5). The seperator character you use is not important. Command: DATEADD <date> <days> <var> Parms: date The date to add to. days The number of days to add var The name of the variable to store the date in. Example: CURDATE 5 '/' xdate ;xdate = "03/14/92" DATEADD xdate 30 xdate ;xdate = xdate + 30 days The command DATEADDM will add the specified number of months to a date field. The date field that is being added to *must* be in 'mm-dd-yy' format (CURDATE format #5). The seperator character you use is not important. If the result of the addition is an invalid day for the month, the day will be set equal to the highest allowable day for that month. For example, if you add 1 month to 01-30-92 the result is 02-30-92. Since February does not have 30 days, it will be adjusted to 02-29-92 (leap year is detected and accounted for). Command: DATEADDM <date> <months> <var> Parms: date The date to add to. months The number of months to add var The name of the variable to store the date in. Example: CURDATE 5 '/' xdate ;xdate = "03/14/92" DATEADDM xdate 1 xdate ;xdate = "04/14/92" CURDATE 5 '/' xdate ;xdate = "12/14/91" DATEADDM xdate 1 xdate ;xdate = "01/14/92" CURDATE 5 '/' xdate ;xdate = "08/30/92" DATEADDM xdate 6 xdate ;xdate = "02/28/93" <- note day The command DATESUB will subtract the specified number of days from a date field. The date field that is being subtracted from *must* be in 'mm-dd-yy' format (CURDATE format #5). The seperator character you use is not important. Command: DATESUB <date> <days> <var> Parms: date The date to add to. days The number of days to subtract. var The name of the variable to store the date in. Example: CURDATE 5 '/' xdate ;xdate = "03/14/92" DATESUB xdate 30 xdate ;xdate = xdate - 30 days The command DATESUBM will subtract the specified number of months from a date field. The date field that is being subtracted from *must* be in 'mm-dd-yy' format (CURDATE format #5). The seperator character you use is not important. If the subtraction results in an invalid day for the month, the day will be set equal to the highest allowable day for that month. For example, if you subtract 1 month from 03-30-92 the result is 02-30-92. Since February does not have 30 days, it will be adjusted to 02-29-92 (leap year is detected and accounted for). Command: DATESUBM <date> <months> <var> Parms: date The date to add to. months The number of months to subtract. var The name of the variable to store the date in. Example: CURDATE 5 '/' xdate ;xdate = "03/14/92" DATESUBM xdate 1 xdate ;xdate = "02/14/92" CURDATE 5 '/' xdate ;xdate = "01/14/92" DATESUBM xdate 1 xdate ;xdate = "12/14/91" CURDATE 5 '/' xdate ;xdate = "03/31/92" DATESUBM xdate 1 xdate ;xdate = "02/29/92" <- note day The command DATEDIF will return the number of days between two date fields. Both date fields *must* be in 'mm-dd-yy' format (CURDATE format #5). The seperator character you use is not important. Command: DATEDIF <date1> <date2> <var> Parms: date1 Date string 1. date2 Date string 2. var The name of the variable to store the date in. Example: CURDATE 5 '/' xdate1 ;xdate1 = "03/14/92" DATEADD xdate1 30 xdate2 ;xdate2 = xdate1 + 30 days DATEDIF xdate1 xdate2 xdif ;xdif = xdate1 - xdate2 Callback Commands ─────────────────────────────────────────────────────────────────────────── SENDMODEM <waitsec> <cmnd> PARSEPHONE <phone#> <area> <exchg> <number> CALLBACK <waitsec> <ATDT + phone #> Caller Data Modification ─────────────────────────────────────────────────────────────────────────── UPDATE_USER_RECORD The SET command, math commands and date/time commands can be used to modify fields in the caller's record. The fields that can be modified are: @city@ City @comment1@ Comment line 1 @comment2@ Comment line 2 @dataphone@ Business/Data Phone @daybytes@ Daily D/L Bytes @dlbytes@ Total D/L Bytes @dlfiles@ Total D/L Files @expdate@ Expiration Date @expertmode@ Expert mode @homephone@ Home/Voice Phone @pagelen@ Page length setting @password@ User password @proltr@ Default Protocol Letter @security@ Security Level @upbytes@ Total U/L Bytes @upfiles@ Total U/L Files Examples: SET @proltr@ 'Z' ;change default protocol to zmodem SET @security@ 10 ;change security level to 10 INC @dlfiles@ ;add 1 to Total D/L Files DATEADDM @expdate@ 1 @expdate@ ;add 1 month to the expire date ; of the caller If you need to change the available online time, use the ADJTIME command. This command will add or subtract a specified number of minutes from the callers remaining online time. Examples: ADJTIME ADD 10 ;add 10 minutes to the callers online time ADJTIME SUB 10 ;subtract 10 minutes from the callers online time To check the caller status in a conference use the GETCINFO command. This command will check a specified flag in the specified conference number. For example, the following example will set 'isCnfReg' to '0' if the caller is NOT registered in conference #1. If the caller IS registered in conference #1, 'isCnfReg' is set to '1'. GETCINFO 1 REGISTERED isCnfReg To set the caller status in a conference use the SETCINFO command. This command will set a specified flag in the specified conference number. For example, the following example will set the REGISTERED flag in the conference record for the caller: SETCINFO 1 REGISTERED TRUE Math Funtions ─────────────────────────────────────────────────────────────────────────── These commands provide basic functions. See SSREF.DOC for a discussion of each. ADD <var> <val1> <val2> SUB <var> <val1> <val2> MUL <var> <val1> <val2> DIV <var> <val1> <val2> INC <var> DEC <var> Display Funtions ─────────────────────────────────────────────────────────────────────────── These commands provide basic functions. See SSREF.DOC for a discussion of each. DISPLAY <row> <col> <..data..> DISPLAYC <row> <..data..> DISPLAY_FILE <file> GOTORC <row> <col> INDENT <cols> REPEAT <row> <col> <char> <cnt> TEXT <..data..> Display Control Funtions ─────────────────────────────────────────────────────────────────────────── CLEARCRT CLEARLINES <row1> <row2> COLOR [BRIGHT] <fcolor> [BLINK] <bcolor> ENTRY_MIN_CHAR <char> ENTRY_MIN_ATTR [BRIGHT] <fcolor> [BLINK] <bcolor> ENTRY_MAX_CHAR <char> ENTRY_MAX_ATTR [BRIGHT] <fcolor> [BLINK] <bcolor> ENTRY_ANS_ATTR [BRIGHT] <fcolor> [BLINK] <bcolor> NEWLINE <count> String Funtions ─────────────────────────────────────────────────────────────────────────── RANDOM_STR <count> <var> SET <var> <val> TRIMR <var> [<var>...<var>] TRIML <var> [<var>...<var>] TRIM <var> [<var>...<var>] LCASE <var> [<var>...<var>] UCASE <var> [<var>...<var>] PARSE <string> GETWORD <var> Script Flow Control Funtions ─────────────────────────────────────────────────────────────────────────── EXIT <ALL> CALL <script> <label> RUN <script> <label> Misc Funtions ─────────────────────────────────────────────────────────────────────────── DOS <cmd> ESET <evar> <val> FREECORE GOODBYE HANGUP INCLUDE <file> LOG_MSG <msg> LOG_DATA <file> MSG SRCHTXTFILE <srchtxt> <file> SHELL <prg> <parms> VALIDCREDITCARD <card#> <var>